feat: propagate structured CipherStash auth refusals - #894

To be honest, I think this PR is the wrong approach. It's doing too much heavy lifting. The error type in stack_auth already implements miette::Diagnostic, So I think we can just add #[diagnostic(transparent)] to the AuthError enum variant on the protect_ffi Error. The stack/protect-ffi layer should be really thin.

StackAuth should include a code, message and instructions on the diagnostic for when CTS returns a 402. Then any consumer of stack_auth, including Proxy would get the same response.

Requesting changes. The engineering is sound — the propagation path is correct where it is live, the Result contract and EncryptionErrorTypes strings are untouched, the test work is unusually rigorous, and CI is fully green including the credentialed live suite. What blocks is prose that ships to customers stating as current behaviour something the pinned dependency provably cannot do yet, plus a pair of docblocks describing a mechanism this PR's own rework deleted. All fixes are text-level.

1. BLOCKING — the CLI half is dormant, but the skills and changeset say it's live

The taxonomy (USAGE_LIMIT_EXCEEDED, ORG_NOT_PROVISIONED, cs_code) ships in stack-auth 0.42.3, published to crates.io 2026-08-26. The npm @cipherstash/auth this PR pins is 0.43.0, published 2026-08-12 — the latest available, and structurally two weeks too old to contain it. I verified both registry timestamps directly, and a byte-search of the published 0.43.0 binaries (darwin-arm64 .node and the wasm build) finds zero occurrences of the taxonomy codes or cs_code, with NOT_AUTHENTICATED present as the positive control; the 0.43.0 AuthFailure union in index.d.ts lacks both types too.

So today, a real CTS 402 during stash env renewal or stash auth login arrives from the auth binding as a pre-taxonomy type, falls through to session_invalid + the login hint — the exact wrong-advice loop this PR exists to kill. Every CLI test mocks @cipherstash/auth, so the suites pin the rendering, not the live path. (The native @cipherstash/stack entry, LockContext.identify(), and @cipherstash/nextjs are live — protect-ffi embeds stack-auth 0.42.3, and the identify/nextjs paths parse the 402 themselves.)

The tests already know this — packages/cli/src/commands/auth/__tests__/failure.test.ts says the lookups "start returning the terminal answer the day the dependency ships the code". The customer-facing text doesn't:

• skills/stash-cli/SKILL.md: "That case reports usage_limit_exceeded…", "fails with USAGE_LIMIT_EXCEEDED on the --json stream"
• skills/stash-auth/SKILL.md: "On the CLI, stash env reports these under their own codes…"
• .changeset/usage-limit-refusal-guidance.md: "stash auth login and stash env now consume @cipherstash/auth 0.43.0's typed failures"

Either gate the PR on an auth release carrying the taxonomy and bump the pin, or reword these three to conditional/future phrasing. Skills land in customer repos; per AGENTS.md a wrong sentence there is a wrong line of code.

2. Dangling AuthDiagnosticRelay + false "verbatim relay" claim in shipped TSDoc

• packages/protect-ffi/src/types.ts and src/index.types.test.ts both say "see AuthDiagnosticRelay in crates/protect-ffi/src/lib.rs" — no such item exists; it's a leftover from the pre-rework design (the rework moved to #[diagnostic(transparent)] and deleted the relay).
• packages/protect-ffi/src/errors.ts (and the tracked dist/wasm/errors.d.ts) claim a config.authStrategy failure's help/url/type are relayed "verbatim — not values re-derived from the stack-auth enum". The implementation does the opposite: neon_failure_to_auth_error drops the reserved keys and reconstructs via AuthError::from_error_code, whose help/url come from the enum's fixed #[diagnostic] attributes, and unknown codes collapse to CUSTOM. A strategy's own remedy text never survives. The type-level test only pins that the type accepts the fields, as its own docblock admits.

3. Minor text fixes

• packages/cli/src/commands/auth/failure.ts: the comment claiming byte-identity with TERMINAL_PUNCTUATION in packages/stack/src/encryption/helpers/auth-failure.ts — that file contains no such constant and no message-joining; no guard compares them. Rework leftover.
• Test narration in identify-cts-refusal.test.ts (and the nextjs twin) says the two legacy codes are "read from error"; neither classifier reads error at all — absent cs_code defaults unconditionally. Behaviour correct, narration wrong.
• Worth one sentence somewhere: auth login --json emits USAGE_LIMIT_EXCEEDED while env --json emits usage_limit_exceeded — each consistent with its command's convention, but an agent consuming both streams matches two spellings of one condition.

Verified clean (no need to re-argue these)

Result contract and error-type strings untouched, all new fields optional/additive across every error shape including bulk per-row items; #[diagnostic(transparent)] cannot leak a foreign code into ProtectErrorCode (checked every crate in the chain for #[diagnostic(code(...))] — none); all 20 operation mappers converted and parameter-tested, with mocks made partial precisely so the real isProtectErrorCode runs; the wasm-inline readErrorCode change closes a genuine accepts-any-string type lie; no native specifier leaks into the wasm bundle; skills touched match the AGENTS.md map and nothing in the untouched skills became false; four changesets present and correctly leveled (modulo the finding-1 sentence); Rust test literals match stack-auth 0.42.3's attributes verbatim; no plaintext/secret logging; CI green including cargo checks and the live integration suite. Also worth saying out loud since the body undersells it: packages/nextjs had no test script at all — its suite was dead until this PR wired it up and repaired it. Good change.

Happy to re-review as soon as the finding-1 wording (or the pin) and the finding-2 docblocks are settled.

Approving at d2a8f08. Every finding from my previous review is resolved, and I re-verified the load-bearing one against the registry rather than the prose:

1. The dormancy is gone — the pin now points at a binding that really carries the taxonomy. @cipherstash/auth 0.44.0 (published today, 03:43Z) is pinned across all seven catalog names together, per the supply-chain rule. I unpacked the published auth-darwin-arm64@0.44.0 binary and found USAGE_LIMIT_EXCEEDED, ORG_NOT_PROVISIONED, and cs_code present (with NOT_AUTHENTICATED as the positive control), and 0.44.0's index.d.ts declares both new members on the AuthFailure union. The changeset and skills' present-tense claims ("now consume 0.44.0's typed failures") are now true statements about the shipping dependency, and CI's credentialed integration suite is green on the bump.
2. The "verbatim relay" claim is rewritten to match the implementation (reconstruction from type + message + variant payload; known codes get the variant's guidance, unknown collapse to CUSTOM, caller help/url not forwarded) — in errors.ts, types.ts, the type test, and the tracked dist/wasm/errors.d.ts. Both dangling AuthDiagnosticRelay references are gone.
3. The TERMINAL_PUNCTUATION byte-identity comment is replaced with the truthful local-presentation note, and the "reads off error" test narrations now say what the classifiers actually do (default to the usage limit).
4. The casing split even got documented — skills/stash-cli now tells agents USAGE_LIMIT_EXCEEDED (login) and usage_limit_exceeded (env) are one condition. That was my optional item; nice to see it land.

The nextjs boundary rationale (don't pull platform binaries into middleware for a string lookup) is also better argued than before. Good rework all round.